<?xml version="1.0" encoding="ascii"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
          "DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>qmanager</title>
  <link rel="stylesheet" href="epydoc.css" type="text/css" />
  <script type="text/javascript" src="epydoc.js"></script>
</head>

<body bgcolor="white" text="black" link="blue" vlink="#204080"
      alink="#204080">
<!-- ==================== NAVIGATION BAR ==================== -->
<table class="navbar" border="0" width="100%" cellpadding="0"
       bgcolor="#a0c0ff" cellspacing="0">
  <tr valign="middle">
  <!-- Home link -->
      <th bgcolor="#70b0f0" class="navbar-select"
          >&nbsp;&nbsp;&nbsp;Home&nbsp;&nbsp;&nbsp;</th>

  <!-- Tree link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Index link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Help link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Project homepage -->
      <th class="navbar" align="right" width="100%">
        <table border="0" cellpadding="0" cellspacing="0">
          <tr><th class="navbar" align="center"
            ><a class="navbar" target="_top" href="http://django-qmanager.googlecode.com">QManager v0.2.1</a></th>
          </tr></table></th>
  </tr>
</table>
<table width="100%" cellpadding="0" cellspacing="0">
  <tr valign="top">
    <td width="100%">
      <span class="breadcrumbs">
        Module&nbsp;qmanager
      </span>
    </td>
    <td>
      <table cellpadding="0" cellspacing="0">
        <!-- hide/show private -->
        <tr><td align="right"><span class="options">[<a href="javascript:void(0);" class="privatelink"
    onclick="toggle_private();">hide&nbsp;private</a>]</span></td></tr>
        <tr><td align="right"><span class="options"
            >[<a href="frames.html" target="_top">frames</a
            >]&nbsp;|&nbsp;<a href="qmanager-module.html"
            target="_top">no&nbsp;frames</a>]</span></td></tr>
      </table>
    </td>
  </tr>
</table>
<!-- ==================== MODULE DESCRIPTION ==================== -->
<h1 class="epydoc">Module qmanager</h1><span class="codelink"><a href="qmanager-pysrc.html">source&nbsp;code</a></span><br /><br />
<p>QManager is an abstracted Django manager which filters via custom queries.</p>
<div class="rst-section">
<h1 class="heading"><a id="rst-introduction" name="rst-introduction">Introduction</a></h1>
<p>The <tt class="rst-docutils literal"><span class="pre">QManager</span></tt> class is a subclass of <tt class="rst-docutils literal"><span class="pre">django.db.models.Manager</span></tt> which can
remove some of the boilerplate in manager definitions. Managers may be used to
define 'table-level' operations on your models, and one of their most common
uses is to provide a pre-defined <tt class="rst-docutils literal"><span class="pre">QuerySet</span></tt> for model data. The typical
programming idiom goes something like this:</p>
<blockquote>
<ol class="rst-arabic">
<li><p class="rst-first">Define your custom manager as a subclass of
<tt class="rst-docutils literal"><span class="pre">django.db.models.Manager</span></tt>, overriding the <tt class="rst-docutils literal"><span class="pre">get_query_set</span></tt> method
to return a filtered query set. For example:</p>
<pre class="rst-literal-block">
class MyManager(models.Manager):
    def get_query_set(self):
        return super(MyManager, self).get_query_set().filter(
            field1='x', field2='y')
</pre>
</li>
<li><p class="rst-first">On your model, instantiate the manager. Following from the previous
example:</p>
<pre class="rst-literal-block">
class MyModel(models.Model):
    field1 = models.CharField(...)
    field2 = models.CharField(...)
    ...
    objects = models.Manager() # Default manager instance.
    my_mgr = MyManager() # Custom manager instance.
</pre>
</li>
</ol>
</blockquote>
</div>
<div class="rst-section">
<h1 class="heading"><a id="rst-usage-of-qmanager" name="rst-usage-of-qmanager">Usage of <tt class="rst-docutils literal"><span class="pre">QManager</span></tt></a></h1>
<p>The problem with this pattern is that it ends up being repeated several times
for each model as you try to define several useful custom managers for each
type of data. The <tt class="rst-docutils literal"><span class="pre">QManager</span></tt> class abstracts this idiom by providing a simple
way of defining managers to return query sets. Now, what originally involved
two parts is now down to one:</p>
<pre class="rst-literal-block">
class MyModel(models.Model):
    field1 = models.CharField(...)
    field2 = models.CharField(...)
    ...
    objects = models.Manager()
    my_mgr = QManager(Q(field1='x', field2='y'))
</pre>
<p>As you can see, a custom manager is defined by passing <tt class="rst-docutils literal"><span class="pre">QManager</span></tt>'s
<tt class="rst-docutils literal"><span class="pre">__init__</span></tt> method a <tt class="rst-docutils literal"><span class="pre">Q</span></tt> object. <tt class="rst-docutils literal"><span class="pre">Q</span></tt> objects are used in Django to specify
queries of arbitrary complexity, and by using <tt class="rst-docutils literal"><span class="pre">QManager</span></tt> you don't need to
write all the boilerplate of the first example: all it takes is a simple <tt class="rst-docutils literal"><span class="pre">Q</span></tt>
object.</p>
<div class="rst-section">
<h2 class="heading"><a id="rst-conjunctions-and-disjunctions" name="rst-conjunctions-and-disjunctions">Conjunctions and Disjunctions</a></h2>
<p>Another feature of <tt class="rst-docutils literal"><span class="pre">Q</span></tt> instances is that they can be combined using the <tt class="rst-docutils literal"><span class="pre">&amp;</span></tt>
(and) and <tt class="rst-docutils literal"><span class="pre">|</span></tt> (or) logical operators. These must not be the Python literal
<tt class="rst-docutils literal"><span class="pre">and</span></tt> and <tt class="rst-docutils literal"><span class="pre">or</span></tt> operators, as they behave differently to the symbols. Let's
say, for example, that you have two query sets defined by <tt class="rst-docutils literal"><span class="pre">Q</span></tt> instances whose
intersection (logical <em>and</em>) you want to find. Each of these query sets would
be defined by an instance of <tt class="rst-docutils literal"><span class="pre">Q</span></tt>, like so:</p>
<pre class="rst-literal-block">
query1 = Q(public=True)
query2 = Q(confirmed=True)
</pre>
<p>Each of these return query sets which contain those records which are public
and confirmed, respectively. Such query sets would be obtained by calling the
<tt class="rst-docutils literal"><span class="pre">filter</span></tt> method on one of the model's managers (i.e. <tt class="rst-docutils literal"><span class="pre">objects</span></tt>). Suppose
you now want to find all the records which are both public <em>and</em> confirmed, in
one query set. Typically, you would define a <tt class="rst-docutils literal"><span class="pre">Q</span></tt> instance such as
<tt class="rst-docutils literal"><span class="pre">Q(public=True,</span> <span class="pre">confirmed=True)</span></tt>, but this violates the DRY principle, as the
same information is repeated. Instead, one may simply do this:</p>
<pre class="rst-literal-block">
query3 = query1 &amp; query2
</pre>
<p>This is a shortcut which allows you to cut down the amount of extra code you
write, and maintain DRY in your code. The <tt class="rst-docutils literal"><span class="pre">QManager</span></tt> class provides a wrapper
which lets you do the same thing in your manager definitions. An example might
be:</p>
<pre class="rst-literal-block">
class MyModel(models.Model):
    public = models.BooleanField()
    confirmed = models.BooleanField()
    ...
    public_objects = QManager(Q(public=True))
    confirmed_objects = QManager(Q(confirmed=True))
    public_confirmed = public_objects &amp; confirmed_objects
</pre>
</div>
<div class="rst-section">
<h2 class="heading"><a id="rst-flexibility-of-qmanager" name="rst-flexibility-of-qmanager">Flexibility of <tt class="rst-docutils literal"><span class="pre">QManager</span></tt></a></h2>
<p>This use of <tt class="rst-docutils literal"><span class="pre">&amp;</span></tt> and <tt class="rst-docutils literal"><span class="pre">|</span></tt> is not restricted to just <tt class="rst-docutils literal"><span class="pre">QManager</span></tt> instances;
<tt class="rst-docutils literal"><span class="pre">Q</span></tt> objects may also be combined with <tt class="rst-docutils literal"><span class="pre">QManager</span></tt> instances via the logical
operators. A caveat, however: in these statements, the <tt class="rst-docutils literal"><span class="pre">QManager</span></tt> instance
<em>must</em> come before the <tt class="rst-docutils literal"><span class="pre">Q</span></tt> instance. It is valid, for example, to do this:</p>
<pre class="rst-literal-block">
public_confirmed = public_objects &amp; Q(confirmed=True)
</pre>
<p>It is an error, however, to do the following:</p>
<pre class="rst-literal-block">
public_confirmed = Q(confirmed=True) &amp; public_objects
</pre>
<p>It is advisable to ensure that errors like these do not happen, as they will be
difficult to debug if they do: an error will most likely be raised somewhere in
the <tt class="rst-docutils literal"><span class="pre">Q</span></tt> class, rather than for <tt class="rst-docutils literal"><span class="pre">QManager</span></tt>.</p>
</div>
<div class="rst-section">
<h2 class="heading"><a id="rst-exclusive-queries" name="rst-exclusive-queries">Exclusive Queries</a></h2>
<p>Another feature of query set manipulation is exclusion. <tt class="rst-docutils literal"><span class="pre">QuerySet</span></tt> and
<tt class="rst-docutils literal"><span class="pre">Manager</span></tt> instances have <tt class="rst-docutils literal"><span class="pre">exclude</span></tt> methods which, when called with a <tt class="rst-docutils literal"><span class="pre">Q</span></tt>
object, will return the set of all data <em>not</em> matching the conditions given in
the query. This is called finding the <em>complement</em> of a set of data, and
<tt class="rst-docutils literal"><span class="pre">QManager</span></tt> instances support this through the inversion operator (<tt class="rst-docutils literal"><span class="pre">~</span></tt>). For
example:</p>
<pre class="rst-literal-block">
class MyModel(models.Model):
    ...
    public_objects = QManager(Q(public=True))
    non_public_objects = ~public_objects
</pre>
<p>If a reference to a <tt class="rst-docutils literal"><span class="pre">QManager</span></tt> instance, whether through their definition
(i.e. <tt class="rst-docutils literal"><span class="pre">~QManager(...)</span></tt>) or a variable (i.e. <tt class="rst-docutils literal"><span class="pre">~public_objects</span></tt>), is
prepended with a <tt class="rst-docutils literal"><span class="pre">~</span></tt> symbol, then it's <tt class="rst-docutils literal"><span class="pre">__invert__</span></tt> magic method will be
called. In the case of <tt class="rst-docutils literal"><span class="pre">QManager</span></tt> instances, this will return a new instance
whose query is defined as the complement of the old query. This may be used in
conjunction with the other operators, for example:</p>
<pre class="rst-literal-block">
class MyModel(models.Model):
    ...
    public_objects = QManager(Q(public=True))
    non_public_confirmed = confirmed_objects &amp; ~public_objects
    non_confirmed_public = ~confirmed_objects &amp; public_objects
</pre>
</div>
<div class="rst-section">
<h2 class="heading"><a id="rst-using-qmanagerfactory-for-refactoring-qmanager-definitions" name="rst-using-qmanagerfactory-for-refactoring-qmanager-definitions">Using <tt class="rst-docutils literal"><span class="pre">QManagerFactory</span></tt> for Refactoring <tt class="rst-docutils literal"><span class="pre">QManager</span></tt> Definitions</a></h2>
<p>A common design pattern which emerges when using <tt class="rst-docutils literal"><span class="pre">QManager</span></tt> is the definition
of queries which apply to several similar models. For example, if several of
your models have <tt class="rst-docutils literal"><span class="pre">public</span></tt> fields which are boolean flags telling whether or
not a record is public, then you may want a manager to get only public records.
Because, however, you are defining managers across several models, the query
<tt class="rst-docutils literal"><span class="pre">Q(public=True)</span></tt> will be repeated several times. If, one day, you decide to
change the field to being called <tt class="rst-docutils literal"><span class="pre">is_public</span></tt>, then each query will have to be
edited individually. A typical set-up might look something like this:</p>
<pre class="rst-literal-block">
class A(models.Model):
    public = models.BooleanField()
    ...
    public_objects = QManager(Q(public=True))

class B(models.Model):
    public = models.BooleanField()
    ...
    public_objects = QManager(Q(public=True))
</pre>
<p>As you can see, because the managers are defined on different models they may
not be reused. A simple way around this is to use the <tt class="rst-docutils literal"><span class="pre">QManagerFactory</span></tt>
function in this module. At the top of your models file (or a separate file for
managers, if you wish), place the following line:</p>
<pre class="rst-literal-block">
PublicManager = QManagerFactory(Q(public=True), name='PublicManager')
</pre>
<p><tt class="rst-docutils literal"><span class="pre">PublicManager</span></tt> will now be a class, with the name 'PublicManager' (due to
the <tt class="rst-docutils literal"><span class="pre">name</span></tt> keyword), which is a subclass of <tt class="rst-docutils literal"><span class="pre">QManager</span></tt>, and has the
<tt class="rst-docutils literal"><span class="pre">query</span></tt> attribute pre-defined as <tt class="rst-docutils literal"><span class="pre">Q(public=True)</span></tt>. On each model, you now
only need to place the following:</p>
<pre class="rst-literal-block">
class A(models.Model):
    public = models.BooleanField()
    ...
    public_objects = PublicManager()
</pre>
<p>And likewise for <tt class="rst-docutils literal"><span class="pre">B</span></tt>. For more information on the <tt class="rst-docutils literal"><span class="pre">QManagerFactory</span></tt>
function, you are advised to consult its docstring and source code.</p>
<p>For more information, esp. implementation details, consult the source code. It
may also be useful to look at the official Django documentation for the <tt class="rst-docutils literal"><span class="pre">Q</span></tt>
class and database API.</p>
</div>
</div><br /><br />

<!-- ==================== CLASSES ==================== -->
<a name="section-Classes"></a>
<table class="summary" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td colspan="2" class="table-header">
    <table border="0" cellpadding="0" cellspacing="0" width="100%">
      <tr valign="top">
        <td align="left"><span class="table-header">Classes</span></td>
        <td align="right" valign="top"
         ><span class="options">[<a href="#section-Classes"
         class="privatelink" onclick="toggle_private();"
         >hide private</a>]</span></td>
      </tr>
    </table>
  </td>
</tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a href="qmanager.QManager-class.html" class="summary-name">QManager</a><br />
      Boilerplate Django manager which filters via a custom query.
    </td>
  </tr>
</table>
<!-- ==================== FUNCTIONS ==================== -->
<a name="section-Functions"></a>
<table class="summary" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td colspan="2" class="table-header">
    <table border="0" cellpadding="0" cellspacing="0" width="100%">
      <tr valign="top">
        <td align="left"><span class="table-header">Functions</span></td>
        <td align="right" valign="top"
         ><span class="options">[<a href="#section-Functions"
         class="privatelink" onclick="toggle_private();"
         >hide private</a>]</span></td>
      </tr>
    </table>
  </td>
</tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="qmanager-module.html#QManagerFactory" class="summary-sig-name">QManagerFactory</a>(<span class="summary-sig-arg">query</span>,
        <span class="summary-sig-arg">name</span>=<span class="summary-sig-default">None</span>)</span><br />
      Construct a <tt class="rst-docutils literal"><span class="pre">QManager</span></tt> subclass with a pre-defined query.</td>
          <td align="right" valign="top">
            <span class="codelink"><a href="qmanager-pysrc.html#QManagerFactory">source&nbsp;code</a></span>
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="qmanager-module.html#get_query" class="summary-sig-name">get_query</a>(<span class="summary-sig-arg">obj</span>)</span><br />
      Given an object, return (somehow) a <tt class="rst-docutils literal"><span class="pre">Q</span></tt> instance.</td>
          <td align="right" valign="top">
            <span class="codelink"><a href="qmanager-pysrc.html#get_query">source&nbsp;code</a></span>
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="qmanager-module.html#get_valid_query" class="summary-sig-name">get_valid_query</a>(<span class="summary-sig-arg">query</span>)</span><br />
      Given an object, return a <tt class="rst-docutils literal"><span class="pre">Q</span></tt> instance, or raise an error.</td>
          <td align="right" valign="top">
            <span class="codelink"><a href="qmanager-pysrc.html#get_valid_query">source&nbsp;code</a></span>
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
</table>
<!-- ==================== VARIABLES ==================== -->
<a name="section-Variables"></a>
<table class="summary" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td colspan="2" class="table-header">
    <table border="0" cellpadding="0" cellspacing="0" width="100%">
      <tr valign="top">
        <td align="left"><span class="table-header">Variables</span></td>
        <td align="right" valign="top"
         ><span class="options">[<a href="#section-Variables"
         class="privatelink" onclick="toggle_private();"
         >hide private</a>]</span></td>
      </tr>
    </table>
  </td>
</tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a name="OLD_VERSION"></a><span class="summary-name">OLD_VERSION</span> = <code title="False">False</code>
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a name="MISSING_CLASSES"></a><span class="summary-name">MISSING_CLASSES</span> = <code title="'Manager, Q and QuerySet'"><code class="variable-quote">'</code><code class="variable-string">Manager, Q and QuerySet</code><code class="variable-quote">'</code></code>
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a href="qmanager-module.html#exc" class="summary-name">exc</a> = <code title="ImportError('Settings cannot be imported, because environment variable\
 DJANGO_SETTINGS_MODULE is undefined.',)">ImportError('Settings cannot be imported, because enviro<code class="variable-ellipsis">...</code></code>
    </td>
  </tr>
</table>
<p class="indent-wrapped-lines"><b>Imports:</b>
  django,
  django.db.models.Manager,
  django.db.models.query.Q,
  django.db.models.query.QuerySet,
  django.db.models.query.QNot,
  django.db.models.query.QOperator
</p><br />
<!-- ==================== FUNCTION DETAILS ==================== -->
<a name="section-FunctionDetails"></a>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td colspan="2" class="table-header">
    <table border="0" cellpadding="0" cellspacing="0" width="100%">
      <tr valign="top">
        <td align="left"><span class="table-header">Function Details</span></td>
        <td align="right" valign="top"
         ><span class="options">[<a href="#section-FunctionDetails"
         class="privatelink" onclick="toggle_private();"
         >hide private</a>]</span></td>
      </tr>
    </table>
  </td>
</tr>
</table>
<a name="QManagerFactory"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">QManagerFactory</span>(<span class="sig-arg">query</span>,
        <span class="sig-arg">name</span>=<span class="sig-default">None</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    ><span class="codelink"><a href="qmanager-pysrc.html#QManagerFactory">source&nbsp;code</a></span>&nbsp;
    </td>
  </table>
  
  <p>Construct a <tt class="rst-rst-docutils literal rst-docutils literal"><span class="pre">QManager</span></tt> subclass with a pre-defined query.</p>
<div class="rst-section">
<h1 class="heading"><a id="rst-introduction" name="rst-introduction">Introduction</a></h1>
<p>The <tt class="rst-docutils literal"><span class="pre">QManagerFactory</span></tt> function returns a new class, subclassed from
<tt class="rst-docutils literal"><span class="pre">QManager</span></tt>, which has its <tt class="rst-docutils literal"><span class="pre">query</span></tt> attribute defined at a class-level,
rather than having to be specified on each instance. This allows the new
class to be instantiated, with no arguments, and return a <tt class="rst-docutils literal"><span class="pre">QManager</span></tt> with
the prescribed query. For more information on how it does this, consult the
docstring and source for <tt class="rst-docutils literal"><span class="pre">QManager.__init__</span></tt>.</p>
<p>A <tt class="rst-docutils literal"><span class="pre">name</span></tt> keyword argument may also be specified, which will be used as
the name of the returned class (by setting the class's <tt class="rst-docutils literal"><span class="pre">__name__</span></tt>
attribute to this value).</p>
</div>
<div class="rst-section">
<h1 class="heading"><a id="rst-usage" name="rst-usage">Usage</a></h1>
<p>This function is useful in cases where a query is needed across several
model definitions, such as when several slightly different models share a
common field, or set of fields, which would benefit from having some
common, pre-defined queries.</p>
<p>An example of this may include having several models which each have images
associated with them via ManyToOne relationships on other models. This may
look something like this (showing only the image classes):</p>
<pre class="rst-literal-block">
...
class AImage(models.Model):
    a = models.ForeignKey(A)
    image = models.ImageField(...)
    public = models.BooleanField()

class BImage(models.Model):
    b = models.ForeignKey(B)
    image = models.ImageField(...)
    public = models.BooleanField()
</pre>
<p>As you can see, each model has a <tt class="rst-docutils literal"><span class="pre">public</span></tt> boolean field. You may wish to
specify managers for the public and non-public images for each. Using the
<tt class="rst-docutils literal"><span class="pre">QManager</span></tt> class, this would be done on each like so:</p>
<pre class="rst-literal-block">
class AImage(models.Model):
    ...
    public_images = QManager(Q(public=True))
    non_public_images = ~public_images

class BImage(models.Model):
    ...
    public_images = QManager(Q(public=True))
    non_public_images = ~public_images
</pre>
<p>As you can see, the query <tt class="rst-docutils literal"><span class="pre">Q(public=True)</span></tt> is repeated on each model
definition. This violates the DRY principle, and so a solution is required
if we are to keep code manageable. By using <tt class="rst-docutils literal"><span class="pre">QManagerFactory</span></tt>, this
problem is solved. Somewhere in your models file (or elsewhere), the
following should be added:</p>
<pre class="rst-literal-block">
PublicImageManager = QManagerFactory(
    Q(public=True), name='PublicImageManager')
</pre>
<p>Then, on each model, the <tt class="rst-docutils literal"><span class="pre">QManager</span></tt> definitions may be replaced by this:</p>
<pre class="rst-literal-block">
class AImage(models.Model):
    ...
    public_images = PublicImageManager()
    non_public_images = ~public_images

class BImage(models.Model):
    ...
    public_images = PublicImageManager()
    non_public_images = ~public_images
</pre>
<p>By doing this, code adheres to DRY, and life is made easier for you, the
developer, by saving space and time. For more information on how subclasses
are constructed, consult this function's source code.</p>
</div>
  <dl class="fields">
  </dl>
</td></tr></table>
</div>
<a name="get_query"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">get_query</span>(<span class="sig-arg">obj</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    ><span class="codelink"><a href="qmanager-pysrc.html#get_query">source&nbsp;code</a></span>&nbsp;
    </td>
  </table>
  
  <p>Given an object, return (somehow) a <tt class="rst-rst-docutils literal rst-docutils literal"><span class="pre">Q</span></tt> instance.</p>
<div class="rst-section">
<h1 class="heading"><a id="rst-usage-and-implementation" name="rst-usage-and-implementation">Usage and Implementation</a></h1>
<p><tt class="rst-docutils literal"><span class="pre">get_query</span></tt> accepts an object, and runs it through several tests to try
and retrieve a query object. These tests are (in this order):</p>
<pre class="rst-literal-block">
1.  If the object is an instance of ``QManager``, return its ``query``
    attribute.

2.  If the object is an instance of ``django.db.models.Manager``, and
    we are using the old version of Django, get its query set, and
    return the ``_filters`` attribute on the ``QuerySet`` instance.

3.  If the object is a ``QuerySet`` instance, and we are using the old
    (pre-1.0) version of Django, return its ``_filters`` attribute.
</pre>
<p>If none of these tests succeed, the object is returned as-is. This
indicates either that the object is already a <tt class="rst-docutils literal"><span class="pre">Q</span></tt> instance, or that it is
of an unknown type.</p>
<p>This function does not validate that objects returned are, in fact, <tt class="rst-docutils literal"><span class="pre">Q</span></tt>
instances. For validation, see the <tt class="rst-docutils literal"><span class="pre">get_valid_query</span></tt> function.</p>
</div>
  <dl class="fields">
  </dl>
</td></tr></table>
</div>
<a name="get_valid_query"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">get_valid_query</span>(<span class="sig-arg">query</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    ><span class="codelink"><a href="qmanager-pysrc.html#get_valid_query">source&nbsp;code</a></span>&nbsp;
    </td>
  </table>
  
  <p>Given an object, return a <tt class="rst-rst-docutils literal rst-docutils literal"><span class="pre">Q</span></tt> instance, or raise an error.</p>
<div class="rst-section">
<h1 class="heading"><a id="rst-introduction" name="rst-introduction">Introduction</a></h1>
<p><tt class="rst-docutils literal"><span class="pre">get_valid_query</span></tt> works by calling <tt class="rst-docutils literal"><span class="pre">get_query</span></tt> on the provided object.
The returned object is then examined using <tt class="rst-docutils literal"><span class="pre">isinstance</span></tt>. If it is not an
instance of <tt class="rst-docutils literal"><span class="pre">django.db.models.query.Q</span></tt>, then a <tt class="rst-docutils literal"><span class="pre">TypeError</span></tt> is raised.
Otherwise, the object is returned.</p>
<p>If using a version of Django below 1.0, then <tt class="rst-docutils literal"><span class="pre">QOperator</span></tt> will be
considered a valid superclass as well. Prior to Django v1.0, the and's,
or's and not's of <tt class="rst-docutils literal"><span class="pre">Q</span></tt> instances were represented by instances of
<tt class="rst-docutils literal"><span class="pre">QAnd</span></tt>, <tt class="rst-docutils literal"><span class="pre">QOr</span></tt> and <tt class="rst-docutils literal"><span class="pre">QNot</span></tt> respectively. The first two are subclasses
of <tt class="rst-docutils literal"><span class="pre">QOperator</span></tt>, the third of <tt class="rst-docutils literal"><span class="pre">Q</span></tt> itself. By testing for subclasses of
<tt class="rst-docutils literal"><span class="pre">QOperator</span></tt> (only with the old version of Django), all query types are
encompassed.</p>
<p>By returning the query, it allows this function to be used wherever a valid
query is required, eliminating a small amount of boilerplate from the
definition from <tt class="rst-docutils literal"><span class="pre">QManager</span></tt>.</p>
</div>
  <dl class="fields">
  </dl>
</td></tr></table>
</div>
<br />
<!-- ==================== VARIABLES DETAILS ==================== -->
<a name="section-VariablesDetails"></a>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td colspan="2" class="table-header">
    <table border="0" cellpadding="0" cellspacing="0" width="100%">
      <tr valign="top">
        <td align="left"><span class="table-header">Variables Details</span></td>
        <td align="right" valign="top"
         ><span class="options">[<a href="#section-VariablesDetails"
         class="privatelink" onclick="toggle_private();"
         >hide private</a>]</span></td>
      </tr>
    </table>
  </td>
</tr>
</table>
<a name="exc"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <h3 class="epydoc">exc</h3>
  
  <dl class="fields">
  </dl>
  <dl class="fields">
    <dt>Value:</dt>
      <dd><table><tr><td><pre class="variable">
ImportError('Settings cannot be imported, because environment variable<span class="variable-linewrap"><img src="crarr.png" alt="\" /></span>
 DJANGO_SETTINGS_MODULE is undefined.',)
</pre></td></tr></table>
</dd>
  </dl>
</td></tr></table>
</div>
<br />
<!-- ==================== NAVIGATION BAR ==================== -->
<table class="navbar" border="0" width="100%" cellpadding="0"
       bgcolor="#a0c0ff" cellspacing="0">
  <tr valign="middle">
  <!-- Home link -->
      <th bgcolor="#70b0f0" class="navbar-select"
          >&nbsp;&nbsp;&nbsp;Home&nbsp;&nbsp;&nbsp;</th>

  <!-- Tree link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Index link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Help link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Project homepage -->
      <th class="navbar" align="right" width="100%">
        <table border="0" cellpadding="0" cellspacing="0">
          <tr><th class="navbar" align="center"
            ><a class="navbar" target="_top" href="http://django-qmanager.googlecode.com">QManager v0.2.1</a></th>
          </tr></table></th>
  </tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%%">
  <tr>
    <td align="left" class="footer">
    Generated by Epydoc 3.0beta1 on Thu Jul 24 09:34:06 2008
    </td>
    <td align="right" class="footer">
      <a href="http://epydoc.sourceforge.net">http://epydoc.sourceforge.net</a>
    </td>
  </tr>
</table>

<script type="text/javascript">
  <!--
  // Private objects are initially displayed (because if
  // javascript is turned off then we want them to be
  // visible); but by default, we want to hide them.  So hide
  // them unless we have a cookie that says to show them.
  checkCookie()
  // -->
</script>
  
</body>
</html>
